Place API
Methods and endpoints
The Place API allows you to:
- search addresses to find your customer’s exact location
- obtain relevant network information associated with a location
- view active and open products as well as ONTs (intact and active) at a location.
The Place API includes the following methods and endpoints:
| Endpoint | Method and endpoint | Function |
|---|---|---|
| API asset version | GET /version | Retrieve API asset full version number (major, minor and patch version numbers) |
| Places By Query | GET /places | Retrieve a list of matching addresses (Places) off supplied address data or PLSAM ID or TUI ID or Product ONT Serial Number |
| Place by ID | GET /places/{placeId} | Retrieve matching address/location (Place) information of supplied Place ID information |
| Site Information By Place ID | GET /places/{placeId}/siteInformation | Retrieve matching address/location (Place) information of supplied Place ID information |
Mandatory attributes
These attributes are mandatory for the Place API:
| Attribute | Description |
|---|---|
| streetName | Used as part of GET /places endpointNote: If no key-based query parameter is supplied, then a street name must be supplied when requesting a search. Name of the street, with no extension (this does not include Street, Avenue or Lane, etc.) |
| tuiId samId productId ontSerialNumber | Used as part of GET /places endpointNote: If no street name is supplied, then a key-based query parameter must be supplied when requesting a search. Key-based parameters include: (TUI ID, PLSAM ID, Product ID, or ONT Serial Number) |
Additional attributes
These additional attributes are also applicable to the Place API.
placesCollection element
| Attribute | Description |
|---|---|
| count | Number of items returned for this request Note: There is a maximum limit of 200 items returned. Learn more about Best Practices: Chorus-IR005 |
| total | Total number of matches in the system. The total indicates the actual number of matches in the system, which may exceed 200 items up to a maximum of 1000 Note: If the total exceeds 200, then only 200 items will be returned |
| items | This is the container of items as an array |
itemInAPlacesCollection element
| Attribute | Description |
|---|---|
| items.id | Unique identifier. See mandatory attributes |
| items.addressType | The type of address recorded for the location: Primary, Greenfield, Pseudo |
| items.locationDescriptor | Description or name that may be associated with an address |
| items.unit | An alphanumeric identifier for a unit type (e.g. an apartment number or a letter) |
| items.unitType | Type of unit (e.g. an apartment or a room) |
| items.level | Floor number in multi-story buildings |
| items.levelType | Type of level (e.g. ground) |
| items.building | Building name |
| items.streetNr | The lower portion of an address range in a street |
| items.streetNrSuffix | Suffix used for an address |
| items.streetNrLast | The upper portion of an address range in a street |
| items.fullStreetNumber | The full street number |
| items.streetName | See mandatory attributes |
| items.streetType | Street type (e.g. Street, Avenue, Lane, etc.) |
| items.suburb | Name of the suburb or locality |
| items.town | Name of the town or city |
| items.postcode | Four-digit postal code |
| items.region | Region name |
| items.additionalKeys | An array of alternate keys for the place as name/value pairs. Valid values are [samId, tuiId] |
additionalKeysNVPair element
| Attribute | Description |
|---|---|
| additionalKeys.name | The type of address key for which the value is provided in the array |
| additionalKeys.value | The value of the address key for the type defined in the corresponding name attribute in the array |
networkLocationInfo
| Attribute | Description |
|---|---|
| networkLocationInfo.mduClass | A numeric class representation of the type of MDU |
| networkLocationInfo.fibreAvailable | Current fibre availability status |
| networkLocationInfo.demandPointType | Describes the dwelling or situation at the address |
| networkLocationInfo.rightOfWay | Flag to indicate if the location is within the right of way (ROW) boundary |
| networkLocationInfo.zoneType | The type of zone |
| networkLocationInfo.greenfield | Flag to indicate if the location is within a greenfield subdivision |
| networkLocationInfo.availabilityStatus | State of our network deployment for the location |
| networkLocationInfo.centralOffice | Code of the Central office feeding the location |
| networkLocationInfo.pointOfInterconnect | UFB Point of Interconnect (POI) that serves the location |
| networkLocationInfo.regionalPointOfInterconnect | Regional Point of Interconnect (POI) that serves the location |
| networkLocationInfo.installType | Type of installation expected to be required |
| networkLocationInfo.installDistance | Distance of installation expected |
| networkLocationInfo.serviceLeadType | Service lead type proposed for new fibre-based service |
| networkLocationInfo.consentRequired | Flag to indicate if consent is required |
| networkLocationInfo.consentCategory | Consent category if applicable for the location |
| networkLocationInfo.consentStatus | Displays the current consent status |
| networkLocationInfo.mduDesignStatus | Current MDU design status |
| networkLocationInfo.mduBuildStatus | Current MDU builds status |
| networkLocationInfo.designRequired | Flag to indicate if design is required |
| networkLocationInfo.buildRequired | Flag to indicate if build is required |
| networkLocationInfo.lfcArea | Name of UFB candidate area |
| networkLocationInfo.buildType | Type of build expected to be required |
| networkLocationInfo.coverageArea | Indicates if Chorus is the Local Fibre Company (LFC) |
| networkLocationInfo.fibreInADayCapable | Flag to indicate if a single visit to install Fibre is possible at the location |
| networkLocationInfo.permitDelayLikely | Flag to indicate if a Permit delay is possible at the location |
| networkLocationInfo.unbundlingCapable | Flag to indicate if Unbundling is possible at the location |
| networkLocationInfo.availabilityDate | Expected date for fibre to be available |
onts
| Attribute | Description |
|---|---|
| item.id | Unique Optical Network Terminal (ONT) identifier |
| item.status | Link status of the Optical Network Terminal (ONT) |
| item.intactOnt | Intact Status of the Optical Network Terminal (ONT) |
| item.serialNumber | Serial number of the Optical Network Terminal (ONT) |
| item.model | Model of the Optical Network Terminal (ONT) |
| item.mode | Mode of the Optical Network Terminal (ONT) |
| item.spareUNIPorts | Spare UNI (Data) ports on an Optical Network Terminal (ONT) |
| item.spareATAPorts | Spare ATA (Voice) ports on an Optical Network Terminal (ONT) |
ontModel
| Attribute | Description |
|---|---|
| item.Model.id | The id for the ontModel |
| item.Model.ontType | Type of the Optical Network Terminal (ONT) |
products
| Attribute | Description |
|---|---|
| item.id | Id of the active product at an address/location |
| item.status | Status of the active product at an address/location |
| item.ontId | Unique Optical Network Terminal (ONT) identifier |
| item.ataPortNumber | ATA (Voice) Port number the service is in use on |
| item.uniPortType | UNI (Data) port type |
| item.uniPortNumber | UNI (Data) Port number the service is in use on |
| item.familyType | Family type of service connected |
| item.productOfferName | Product offer name of service connected |
| item.offerType | Type of offer |
| item.ownedByRSP | Flag to indicate if service shown is owned by RSP |
productOrders
| Attribute | Description |
|---|---|
| item.id | Only returned if the order is owned by requesting RSP |
| item.orderType | Type of order |
| item.providerReference | Only returned if the order is owned by requesting RSP |
| item.ownedByRSP | Flag to indicate if service shown is owned by RSP |
| item.orderDate | Flag to indicate if service shown is owned by RSP |
| item.rfsDateTime | RFS Date Time for the order and includes the disconnect rfs date time |
| item.state | State of the order |
| item.substate | Substate of the order |
| item.product | Product instance related to the inflight order |
Note: For more information on all available resources, attributes, parameters, field types, length and other restrictions, see the API Specification.